If you have questions or suggestions you can contact me on the Internet at:
102620.1554@compuserve.com
*********
*** LEGAL
*********
The author makes NO WARRANTY or representation, either express or implied, with respect to this software, its quality, accuracy, merchantability, or fitness for a particular purpose. This software is provided "AS IS", and you, its user, assume the entire risk as to its quality and accuracy.
Permission for use of this software is granted only if the user accepts full responsibility for any undesirable consequences; the author accepts NO LIABILITY for damages of any kind.
This software is copyright (C) 1996, Luke S. Tomasello.
-a ............... About. (Use -Ar for unformatted output.)
This switch displays this document. This document gives copyright, usage and other information about Pst. The -a switch does simple text formatting to your screen. If you wish to print this document I suggest dumping the document to a text file then printing it from your favorite word processor. To dump this document to a file in raw format, do the following:
Pst -Ar > myfile.txt
-b ............... Leave backup files
This switch leaves backup files just in case you change your mind.
Backup files keep the same name as the input file and only change the extension to .~nn where nn is a hexadecimal number in the range 00-64.
For example, say you run Pst on Myfile.cpp and Myfile.h. The Pst backup files would be Myfile.~00 and Myfile.~01 respectively.
The Backup option is limited to 100 (64h) unique extensions for backup files with the same name.
-c ............... Ignore case
When the Ignore Case options is enabled, text with differing case still match. For example "CAT" would match "cat" and "Cat".
-f ............... Find but don't replace strings
The Find option is used to locate Tokens in a text file. The Tokens mentioned here have all of the same characteristics as the Tokens in replace mode.
See Also: "WHAT IS A TOKEN?"
-h ............... Command summary
The Help option displays a short command summary screen.
-p ............... Preserve mixed case format
Preserve the mixed case nature of the matched string.
Note: -p implies -c.
Here are some examples of what Pst does.
If you were to specify: Pst -p "myfile" "YourFile" *.cpp
If Pst found "myfile", Pst would replace it with "yourfile"
If Pst found "MYFILE", Pst would replace it with "YOURFILE"
If Pst found "MyFile", Pst would replace it with "YourFile"
The rule is: If the found text is all lower case, the replace text is lower cased before the replacement. Else If the found text is all upper case, the replace text is upper cased before the replacement. Else the replacement text is used as is.
-q ............... Quite mode
Quiet mode is useful for batch operation when a bunch of blather is not useful. It is also useful to note that output is slow. In one test I ran with hundreds of replacements over a couple dozen files, 54% of the running time was spent in the output routines! Usually this is not a problem, but it is good to know just the same.
-s ............... Replace substrings
Don't be fooled, these substrings are substrings within Tokens and are not arbitrary.
For Example: If LONG_RETURN is a token then any substring of LONG_RETURN is valid. Eg. "LONG", "G_R", "RET", etc..
Using substring replacements we could change:
LONG_RETURN ==> LONG_UNION
SHORT_RETURN ==> SHORT_UNION
With the following Pst command:
Pst -s _RETURN _UNION *.cpp
*********
*** WHEN AND WHY TO USE PST
*********
Pst is a text processing tool used to to Locate and Replace text Tokens in text files (Usually program source code).
Understanding Text Tokens is key to getting the most out of Pst.
WHAT IS A TOKEN?
A Token is any string of one or more characters in the set [a-zA-Z0-9_].
As far as Pst is concerned, there are only two things in a text file-tokens and delimiters. To Pst, delimiters are all things that are not Tokens.
HOW DOES IT WORK?
Pst locates all of those things it considers Tokens then applies the transformations the user has specified.
IS IT USEFUL?
This model while restrictive is also very powerful and intuitive. I have used several tools such as gres, sed, awk, etc. and found them complicated to use because of their generality. Pst on the other hand implements some of the more frequently used regular expressions 'internally' for text file translation thus simplifying the interface.
WHAT ABOUT SAFETY?
Pst is very careful with "Our" input files.
Pst was designed to preserve the original input file at all costs.
Because Pst never opens the original input file for anything but read, Pst can gracefully report exceptions and continue with the next file in the input queue without ever endangering the original input file.
Pst contains one small module called the critical_rename_service() This is the only code block that can cause data loss. If a failure happens in this module, the program will exit with a full explanation of where your original file is. (It may have already been renamed to something else.)
*********
*** REGISTERATION
*********
Evaluation and Registration:
This is not free software. You are hereby licensed to use this software for evaluation purposes without charge for a period of 21 days. If you use this software after the 21 day evaluation period a registration fee of $8 is required. Payments must be in US dollars drawn on a US bank. Contact Luke S. Tomasello on the Internet at 102620.1554@compuserve.com for payment options. Quantity discounts are also available. When payment is received you will receive a registered copy of the latest version of Pst.
Unregistered use of Pst after the 21-day evaluation period is in violation of U.S. and international copyright laws.
Distribution:
Provided that you verify that you are distributing the Shareware Version (run Pst -h to display whether Registered or Shareware) you are hereby licensed to make as many copies of the Shareware version of this software and documentation as you wish; give exact copies of the original Shareware version to anyone; and distribute the Shareware version of the software and documentation in its unmodified form via electronic means. There is no charge for any of the above.
You are specifically prohibited from charging, or requesting donations, for any such copies, however made; and from distributing the software and/or documentation with other products (commercial or otherwise) without prior written permission, with one exception: Disk Vendors approved by the Association of Shareware Professionals are permitted to redistribute Pst, subject to the conditions in this license, without specific written permission.
